package com.ruoyi.common.annotation;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
import java.math.BigDecimal;

import org.apache.poi.ss.usermodel.HorizontalAlignment;
import org.apache.poi.ss.usermodel.IndexedColors;
import com.ruoyi.common.utils.poi.ExcelHandlerAdapter;

/**
 * 自定义导出Excel数据注解
 * <p>
 * 该注解用于标记实体类的字段，以便在导出Excel时根据配置进行格式化、排序、样式设置等操作。
 * 支持多种数据类型和复杂格式控制，如日期格式化、字典翻译、BigDecimal精度控制、列宽高设置、
 * 单元格样式（颜色、对齐方式）、合并单元格、统计汇总等功能。
 * </p>
 *
 * @author ruoyi
 */
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.FIELD)
public @interface Excel {

    /**
     * 导出时在excel中排序
     * <p>数值越小越靠前，默认为最大整数值表示不参与排序。</p>
     */
    public int sort() default Integer.MAX_VALUE;

    /**
     * 导出到Excel中的列名
     * <p>如果未指定，则使用字段名称作为默认列名。</p>
     */
    public String name() default "";

    /**
     * 日期格式化模式
     * <p>例如："yyyy-MM-dd"，仅对Date或LocalDate等日期类型字段生效。</p>
     */
    public String dateFormat() default "";

    /**
     * 字典类型标识
     * <p>用于从系统字典中获取值对应的标签。例如："sys_user_sex"</p>
     */
    public String dictType() default "";

    /**
     * 内容转换表达式
     * <p>将字段值映射为可读文本，例如："0=男,1=女,2=未知"</p>
     */
    public String readConverterExp() default "";

    /**
     * 分隔符
     * <p>用于分割字符串数组或集合内容，默认为英文逗号","</p>
     */
    public String separator() default ",";

    /**
     * BigDecimal 精度控制
     * <p>默认值-1表示不启用格式化；大于等于0时启用指定小数位数。</p>
     */
    public int scale() default -1;

    /**
     * BigDecimal 舍入规则
     * <p>默认采用四舍五入策略（BigDecimal.ROUND_HALF_EVEN）</p>
     */
    public int roundingMode() default BigDecimal.ROUND_HALF_EVEN;

    /**
     * 列高度（单位：磅）
     * <p>默认值为14磅</p>
     */
    public double height() default 14;

    /**
     * 列宽度（单位：字符宽度）
     * <p>默认值为16个字符宽度</p>
     */
    public double width() default 16;

    /**
     * 值后缀
     * <p>例如添加百分号%，90 → 90%</p>
     */
    public String suffix() default "";

    /**
     * 当字段值为空时使用的默认值
     * <p>避免导出空单元格影响阅读体验</p>
     */
    public String defaultValue() default "";

    /**
     * 单元格提示信息
     * <p>鼠标悬停时显示的提示文字</p>
     */
    public String prompt() default "";

    /**
     * 是否允许内容自动换行
     * <p>默认为false，即不换行</p>
     */
    public boolean wrapText() default false;

    /**
     * 下拉框选项列表
     * <p>设置该列只能选择不能手动输入的内容</p>
     */
    public String[] combo() default {};

    /**
     * 是否从字典中读取combo选项
     * <p>需要配合dictType使用，默认为false</p>
     */
    public boolean comboReadDict() default false;

    /**
     * 是否需要纵向合并单元格
     * <p>适用于包含集合数据的字段，如List类型字段</p>
     */
    public boolean needMerge() default false;

    /**
     * 是否导出该字段
     * <p>可用于生成模板文件，标题存在但内容需用户填写</p>
     */
    public boolean isExport() default true;

    /**
     * 关联对象属性路径
     * <p>支持多级访问，例如："user.department.name"</p>
     */
    public String targetAttr() default "";

    /**
     * 是否自动统计数据总和
     * <p>在最后一行追加统计结果</p>
     */
    public boolean isStatistics() default false;

    /**
     * 单元格数据类型
     * <p>支持数字、字符串、图片、文本等类型</p>
     */
    public ColumnType cellType() default ColumnType.STRING;

    /**
     * 表头背景颜色
     * <p>默认为灰色（GREY_50_PERCENT）</p>
     */
    public IndexedColors headerBackgroundColor() default IndexedColors.GREY_50_PERCENT;

    /**
     * 表头字体颜色
     * <p>默认为白色</p>
     */
    public IndexedColors headerColor() default IndexedColors.WHITE;

    /**
     * 数据单元格背景颜色
     * <p>默认为白色</p>
     */
    public IndexedColors backgroundColor() default IndexedColors.WHITE;

    /**
     * 数据单元格字体颜色
     * <p>默认为黑色</p>
     */
    public IndexedColors color() default IndexedColors.BLACK;

    /**
     * 单元格内容对齐方式
     * <p>默认居中对齐</p>
     */
    public HorizontalAlignment align() default HorizontalAlignment.CENTER;

    /**
     * 自定义数据处理器类
     * <p>实现ExcelHandlerAdapter接口以处理特殊逻辑</p>
     */
    public Class<?> handler() default ExcelHandlerAdapter.class;

    /**
     * 自定义处理器参数
     * <p>传递给handler类的额外参数</p>
     */
    public String[] args() default {};

    /**
     * 字段用途类型
     * <p>ALL: 导入导出都可用；EXPORT: 仅导出；IMPORT: 仅导入</p>
     */
    Type type() default Type.ALL;

    /**
     * 字段用途枚举
     */
    public enum Type {
        ALL(0), EXPORT(1), IMPORT(2);
        private final int value;

        Type(int value) {
            this.value = value;
        }

        public int value() {
            return this.value;
        }
    }

    /**
     * Excel列数据类型枚举
     */
    public enum ColumnType {
        NUMERIC(0), STRING(1), IMAGE(2), TEXT(3);
        private final int value;

        ColumnType(int value) {
            this.value = value;
        }

        public int value() {
            return this.value;
        }
    }
}
